<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qqmlsettings.cpp -->
  <title>Settings QML 类型 | Qt Quick 5.12.3</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="../qtdoc/index.html">Qt 5.12</a></td><td ><a href="qtquick-index.html">Qt Quick 模块</a></td><td ><a href="qtquick-qmlmodule.html">QML类型</a></td><td >Settings QML 类型</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtquick-index.html">Qt 5.12.3 参考指南</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">目录</a></h3>
<ul>
<li class="level1"><a href="#properties">属性</a></li>
<li class="level1"><a href="#methods">Methods</a></li>
<li class="level1"><a href="#details">详细信息</a></li>
<li class="level2"><a href="#application-identifiers">Application Identifiers</a></li>
<li class="level2"><a href="#categories">Categories</a></li>
<li class="level2"><a href="#notes">Notes</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Settings QML 类型</h1>
<span class="subtitle"></span>
<!-- $$$Settings-brief -->
<p>Provides persistent platform-independent application settings. <a href="#details">更多...</a></p>
<!-- @@@Settings -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> 导入语句：</td><td class="memItemRight bottomAlign"> import Qt.labs.settings 1.0</td></tr></table></div><ul>
<li><a href="qml-qt-labs-settings-settings-members.html">所有成员的列表，包括继承成员</a></li>
</ul>
<a name="properties"></a>
<h2 id="properties">属性</h2>
<ul>
<li class="fn"><b><b><a href="qml-qt-labs-settings-settings.html#category-prop">category</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qt-labs-settings-settings.html#fileName-prop">fileName</a></b></b> : string</li>
</ul>
<a name="methods"></a>
<h2 id="methods">Methods</h2>
<ul>
<li class="fn"><b><b><a href="qml-qt-labs-settings-settings.html#setValue-method">setValue</a></b></b>(string <i>key</i>,  var <i>value</i>)</li>
<li class="fn">var <b><b><a href="qml-qt-labs-settings-settings.html#value-method">value</a></b></b>(string <i>key</i>,  var <i>defaultValue</i>)</li>
</ul>
<!-- $$$Settings-description -->
<a name="details"></a>
<h2 id="details">详细信息</h2>
<p>The Settings type provides persistent platform-independent application settings.</p>
<p><b>Note: </b>This type is made available by importing the <b>Qt.labs.settings</b> module. <i>Types in the Qt.labs module are not guaranteed to remain compatible in future versions.</i></p><p>Users normally expect an application to remember its settings (window sizes and positions, options, etc.) across sessions. The Settings type enables you to save and restore such application settings with the minimum of effort.</p>
<p>Individual setting values are specified by declaring properties within a Settings element. All <a href="../qtqml/qtqml-typesystem-basictypes.html">basic type</a> properties are supported. The recommended approach is to use property aliases in order to get automatic property updates both ways. The following example shows how to use Settings to store and restore the geometry of a window.</p>
<pre class="qml">

  import QtQuick.Window 2.1
  import Qt.labs.settings 1.0

  <span class="type"><a href="qml-qtquick-window-window.html">Window</a></span> {
      <span class="name">id</span>: <span class="name">window</span>

      <span class="name">width</span>: <span class="number">800</span>
      <span class="name">height</span>: <span class="number">600</span>

      <span class="type"><a href="qml-qt-labs-settings-settings.html">Settings</a></span> {
          property <span class="type">alias</span> <span class="name">x</span>: <span class="name">window</span>.<span class="name">x</span>
          property <span class="type">alias</span> <span class="name">y</span>: <span class="name">window</span>.<span class="name">y</span>
          property <span class="type">alias</span> <span class="name">width</span>: <span class="name">window</span>.<span class="name">width</span>
          property <span class="type">alias</span> <span class="name">height</span>: <span class="name">window</span>.<span class="name">height</span>
      }
  }

</pre>
<p>At first application startup, the window gets default dimensions specified as 800x600. Notice that no default position is specified - we let the window manager handle that. Later when the window geometry changes, new values will be automatically stored to the persistent settings. The second application run will get initial values from the persistent settings, bringing the window back to the previous position and size.</p>
<p>A fully declarative syntax, achieved by using property aliases, comes at the cost of storing persistent settings whenever the values of aliased properties change. Normal properties can be used to gain more fine-grained control over storing the persistent settings. The following example illustrates how to save a setting on component destruction.</p>
<pre class="qml">

  import QtQuick 2.1
  import Qt.labs.settings 1.0

  <span class="type"><a href="qml-qtquick-item.html">Item</a></span> {
      <span class="name">id</span>: <span class="name">page</span>

      <span class="name">state</span>: <span class="name">settings</span>.<span class="name">state</span>

      <span class="name">states</span>: [
          <span class="type"><a href="qml-qtquick-state.html">State</a></span> {
              <span class="name">name</span>: <span class="string">&quot;active&quot;</span>
              <span class="comment">// ...</span>
          },
          <span class="type"><a href="qml-qtquick-state.html">State</a></span> {
              <span class="name">name</span>: <span class="string">&quot;inactive&quot;</span>
              <span class="comment">// ...</span>
          }
      ]

      <span class="type"><a href="qml-qt-labs-settings-settings.html">Settings</a></span> {
          <span class="name">id</span>: <span class="name">settings</span>
          property <span class="type"><a href="../qtqml/qml-string.html">string</a></span> <span class="name">state</span>: <span class="string">&quot;active&quot;</span>
      }

      <span class="name">Component</span>.onDestruction: {
          <span class="name">settings</span>.<span class="name">state</span> <span class="operator">=</span> <span class="name">page</span>.<span class="name">state</span>
      }
  }

</pre>
<p>Notice how the default value is now specified in the persistent setting property, and the actual property is bound to the setting in order to get the initial value from the persistent settings.</p>
<a name="application-identifiers"></a>
<h2 id="application-identifiers">Application Identifiers</h2>
<p>Application specific settings are identified by providing application <a href="../qtcore/qcoreapplication.html#applicationName-prop">name</a>, <a href="../qtcore/qcoreapplication.html#organizationName-prop">organization</a> and <a href="../qtcore/qcoreapplication.html#organizationDomain-prop">domain</a>, or by specifying <a href="qml-qt-labs-settings-settings.html#fileName-prop">fileName</a>.</p>
<pre class="cpp">

  <span class="preprocessor">#include &lt;QGuiApplication&gt;</span>
  <span class="preprocessor">#include &lt;QQmlApplicationEngine&gt;</span>

  <span class="type"><a href="../qtqml/qml-int.html">int</a></span> main(<span class="type"><a href="../qtqml/qml-int.html">int</a></span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span>argv<span class="operator">[</span><span class="operator">]</span>)
  {
      <span class="type">QGuiApplication</span> app(argc<span class="operator">,</span> argv);
      app<span class="operator">.</span>setOrganizationName(<span class="string">&quot;Some Company&quot;</span>);
      app<span class="operator">.</span>setOrganizationDomain(<span class="string">&quot;somecompany.com&quot;</span>);
      app<span class="operator">.</span>setApplicationName(<span class="string">&quot;Amazing Application&quot;</span>);

      <span class="type">QQmlApplicationEngine</span> engine(<span class="string">&quot;main.qml&quot;</span>);
      <span class="keyword">return</span> app<span class="operator">.</span>exec();
  }

</pre>
<p>These are typically specified in C++ in the beginning of <code>main()</code>, but can also be controlled in QML via the following properties:</p>
<ul>
<li><a href="../qtqml/qml-qtqml-qt.html#application-prop">Qt.application.name</a>,</li>
<li><a href="../qtqml/qml-qtqml-qt.html#application-prop">Qt.application.organization</a> and</li>
<li><a href="../qtqml/qml-qtqml-qt.html#application-prop">Qt.application.domain</a>.</li>
</ul>
<a name="categories"></a>
<h2 id="categories">Categories</h2>
<p>Application settings may be divided into logical categories by specifying a category name via the <a href="qml-qt-labs-settings-settings.html#category-prop">category</a> property. Using logical categories not only provides a cleaner settings structure, but also prevents possible conflicts between setting keys.</p>
<p>If several categories are required, use several Settings objects, each with their own category:</p>
<pre class="qml">

  <span class="type"><a href="qml-qtquick-item.html">Item</a></span> {
      <span class="name">id</span>: <span class="name">panel</span>

      <span class="name">visible</span>: <span class="number">true</span>

      <span class="type"><a href="qml-qt-labs-settings-settings.html">Settings</a></span> {
          <span class="name">category</span>: <span class="string">&quot;OutputPanel&quot;</span>
          property <span class="type">alias</span> <span class="name">visible</span>: <span class="name">panel</span>.<span class="name">visible</span>
          <span class="comment">// ...</span>
      }

      <span class="type"><a href="qml-qt-labs-settings-settings.html">Settings</a></span> {
          <span class="name">category</span>: <span class="string">&quot;General&quot;</span>
          property <span class="type">alias</span> <span class="name">fontSize</span>: <span class="name">fontSizeSpinBox</span>.<span class="name">value</span>
          <span class="comment">// ...</span>
      }
  }

</pre>
<p>Instead of ensuring that all settings in the application have unique names, the settings can be divided into unique categories that may then contain settings using the same names that are used in other categories - without a conflict.</p>
<a name="notes"></a>
<h2 id="notes">Notes</h2>
<p>The current implementation is based on <a href="../qtcore/qsettings.html">QSettings</a>. This imposes certain limitations, such as missing change notifications. Writing a setting value using one instance of Settings does not update the value in another Settings instance, even if they are referring to the same setting in the same category.</p>
<p>The information is stored in the system registry on Windows, and in XML preferences files on <a href="../qtdoc/internationalization.html#macos">macOS</a>. On other Unix systems, in the absence of a standard, INI text files are used. See <a href="../qtcore/qsettings.html">QSettings</a> documentation for more details.</p>
<p><b>请参考 </b><a href="../qtcore/qsettings.html">QSettings</a>。</p>
<!-- @@@Settings -->
<h2>属性文档</h2>
<!-- $$$category -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="category-prop">
<td class="tblQmlPropNode"><p>
<a name="category-prop"></a><span class="name">category</span> : <span class="type"><a href="../qtqml/qml-string.html">string</a></span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This property holds the name of the settings category.</p>
<p>Categories can be used to group related settings together.</p>
</div></div><!-- @@@category -->
<br/>
<!-- $$$fileName -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="fileName-prop">
<td class="tblQmlPropNode"><p>
<a name="fileName-prop"></a><span class="name">fileName</span> : <span class="type"><a href="../qtqml/qml-string.html">string</a></span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This property holds the path to the settings file. If the file doesn't already exist, it is created.</p>
<p>This property was introduced in  Qt 5.12.</p>
<p><b>请参考 </b><a href="../qtcore/qsettings.html#fileName">QSettings::fileName</a> 和 <a href="../qtcore/qsettings.html#Format-enum">QSettings::IniFormat</a>。</p>
</div></div><!-- @@@fileName -->
<br/>
<h2>Method Documentation</h2>
<!-- $$$setValue -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="setValue-method">
<td class="tblQmlFuncNode"><p>
<a name="setValue-method"></a><span class="name">setValue</span>(<span class="type"><a href="../qtqml/qml-string.html">string</a></span> <i>key</i>,  <span class="type"><a href="../qtqml/qml-var.html">var</a></span> <i>value</i>)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Sets the value of setting key to value. If the key already exists, the previous value is overwritten.</p>
<p>This method was introduced in  Qt 5.12.</p>
<p><b>请参考 </b><a href="qml-qt-labs-settings-settings.html#value-method">value()</a> 和 <a href="../qtcore/qsettings.html#setValue">QSettings::setValue</a>。</p>
</div></div><!-- @@@setValue -->
<br/>
<!-- $$$value -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="value-method">
<td class="tblQmlFuncNode"><p>
<a name="value-method"></a><span class="type"><a href="../qtqml/qml-var.html">var</a></span> <span class="name">value</span>(<span class="type"><a href="../qtqml/qml-string.html">string</a></span> <i>key</i>,  <span class="type"><a href="../qtqml/qml-var.html">var</a></span> <i>defaultValue</i>)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Returns the value for setting <i>key</i>. If the setting doesn't exist, returns <i>defaultValue</i>.</p>
<p>This method was introduced in  Qt 5.12.</p>
<p><b>请参考 </b><a href="qml-qt-labs-settings-settings.html#setValue-method">setValue()</a> 和 <a href="../qtcore/qsettings.html#value">QSettings::value</a>。</p>
</div></div><!-- @@@value -->
<br/>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2019 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br/>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br/>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
